home *** CD-ROM | disk | FTP | other *** search
/ Chip 2000 May / Chip_2000-05_cd1.bin / sharewar / FFE / HELP.SWG / 0003_TP7 HELP.pas < prev    next >
Pascal/Delphi Source File  |  1996-09-04  |  15KB  |  391 lines
  1. Submitted by: Derek Powles <derek.powles@eng.ox.ac.uk>
  2.  
  3. Subject: Re Help File format
  4.  
  5. Expanded information on Help File sources.
  6.    In an earlier message I referred to four authors For the book in (1)
  7. below - my mistake - there are three.
  8.     Derek
  9.  
  10. (1)  'A  Programmer's  Guide  to Turbo  Vision'  by  Ertl,  Machholz and
  11. Golgath,  authored  by the Pascal product  management team at Borland in
  12. Germany.  Pub.  Addison-Wesley,  ISBN  0-201-62401-X.  The book contains
  13. chapter  12 ( 18 pages ) describing  how to add a conText sensitive help
  14. Unit  to your own TV Program. The use  of TVHC is described ( 2 pages ).
  15. TVHC   generates  helptxt.pas  and  helptxt.hlp  Files  from  a  special
  16. helptxt.txt  File.  The .pas File is included  in your main routine as a
  17. Unit.  The  HelpFile Unit is also needed,  this Unit, TVHC and a working
  18. example are in the TVDEMO subdirectory. This .hlp File is not compatible
  19. With  the Borland supplied Dos help Files, these have a name of the form
  20. *.t*h.  I believe I am correct in stating that, other than demohelp.hlp,
  21. all supplied *.hlp Files are For Windows use.
  22.  
  23. (2)  The  'Borland Open Architecture  Handbook For Pascal' describes and
  24. supplies  the  Program  HL.EXE. Chapter 8  tells  you '...how to create,
  25. build, and maintain Borland Dos Help Files'. I have attached information
  26. gleaned from this book. There are two sections, the first is information
  27. taken from the book and the second is a Unit holding data structures.
  28.  
  29. look For the *****cut here*****.
  30.  
  31. ******************cut here*********************
  32. {  See `Borland Open Architecture Handbook For Pascal' pages 170-177 }
  33. (***************************************************************
  34. Binary help File format -
  35.  
  36. Records are grouped in four sections
  37.  
  38.  1 - File stamp
  39.  2 - File signature
  40.  3 - File version
  41.  4 - Record Headers
  42.    a - File header Record
  43.    b - conText
  44.    c - Text
  45.    d - keyWord
  46.    e - index
  47.    f - compression Record
  48.    g - indextags {= subheadings, = qualifiers}
  49.  
  50.    ***************************************************************
  51.  
  52.  1 - A File stamp is a null terminated String, note case,
  53.       `TURBO PASCAL HelpFile.\0' or
  54.       `TURBO C Help File.\0'  identifying the File in readable form.
  55.       The null Character is followed by a Dos end-of-File Charcater $1A.
  56.       This is defined as ;STAMP in the help source File.
  57.  
  58.  2 - The File signature For Borland products is a null terminated
  59.       String `$*$* &&&&$*$' (no quotes in help Files).
  60.       This is defined as ;SIGNATURE in the help source File.
  61.  
  62.  3 - The File version is a Record of two Bytes that define the version
  63.       of help format and the help File Text respectively,
  64.  
  65.       Type
  66.         TPVersionRec    = Record
  67.           Formatversion : Byte;
  68.           TextVersion   : Byte   {defined With ;VERSION}
  69.           { this is For info only }
  70.         end;
  71.       FormatVersion For BP7     = $34
  72.                         TP6     = $33
  73.                         TP5     = $04
  74.                         TP4     = $02
  75.                         TC++3.0 = $04
  76.  
  77.  4 - Record Headers -
  78.   All the remaining Records have a common format that includes a header
  79.   identifying the Record's Type and length.
  80.  
  81.     Type
  82.       TPrecHdr  = Record;
  83.         RecType   : Byte;
  84.         RecLength : Word;
  85.       end;
  86.  
  87.   Field RecType is a code that identifies the Record Type.
  88.     Type
  89.       RecType =
  90.         (RT_FileHeader,    {0}
  91.          RT_ConText,       {1}
  92.          RT_Text,          {2}
  93.          RT_KeyWord,       {3}
  94.          RT_Index,         {4}
  95.          RT_Compression);  {5}
  96.          RT_IndexTags,     {6 - only in FormatVersion $34}
  97.  
  98. Field RecLength gives the length of the contents of the Record in Bytes,
  99. not  including the Record header. The contents begin With the first Byte
  100. following the header.
  101.  
  102.   The field `RecType' Types are explained in the following Text.
  103.  
  104. Although  this structure allows an  arbitrary order of Records, existing
  105. Borland products assume a fixed Record ordering as follows:-
  106.         File header Record
  107.         compression Record
  108.         conText table
  109.         index table
  110.         indextags Record {introduced in BP7}
  111.         Text Record
  112.         keyWord Record
  113.  
  114.  4.a The File header Record defines Various parameters and options
  115.   common to the help File.
  116.  
  117.   Type
  118.     TPFileHdrRec     = Record
  119.       Options        : Word;
  120.       MainIndexScreen: Word;
  121.       Maxscreen size : Word;
  122.       Height         : Byte;
  123.       Width          : Byte;
  124.       LeftMargin     : Byte;
  125.     end;
  126.  
  127.       Options - is a bitmapped field. Only one option currently
  128.                 supported.
  129.                 OF_CaseSense ($0004) (C only, not Pascal)
  130.                   if set, index tokens are listed in mixed case
  131.                   in the Index Record, and index searches will
  132.                   be Case sensitive.
  133.                   if cleared, index tokens are all uppercase in
  134.                   the Index Record, and index searches will ignore
  135.                   case.
  136.                   Defined With ;CASESENSE.
  137.  
  138.       MainIndexScreen - this is the number assigned to the conText
  139.                   designated by the ;MAININDEX command in the help
  140.                   source File.
  141.                   if ;MAININDEX is not used, MainIndexScreen is set
  142.                   to zero.
  143.  
  144.       MaxScreenSize - this is the number of Bytes in the longest Text
  145.                   Record in the File (not including the header). This
  146.                   field is not currently in use.
  147.  
  148.       Height, Width - This is the default size in rows and columns,
  149.                   respectively, of the display area of a help Window.
  150.                   Defined With ;HEIGHT and ;WIDTH.
  151.  
  152.       LeftMargin - Specifies the number of columns to leave blank on
  153.                   the left edge of all rows of help Text displayed.
  154.                   Defined With ;LEFTMARGIN.
  155.  
  156.  4.b ConText table -
  157. This  is a table of Absolute File  offsets that relates Help conTexts to
  158. their  associated Text. The first Word of the Record gives the number of
  159. conTexts  in the table. The remainder of the  Record is a table of n ( n
  160. given  by  first  Word)  3-Byte Integers  (LSByte  first).  The table is
  161. indexed  by  conText  number (0 to n-1).  The  3-Byte Integer at a given
  162. index is an Absolute Byte that is offset in the Help File where the Text
  163. of  the  associated  conText begins. The  3-Byte  Integer is signed (2's
  164. complement). Two special values are defined -
  165.         -1 use Index Screen Text (defined in File Header Record).
  166.         -2 no help available For this conText.
  167.   ConText table entry 0 is not used.
  168.  
  169.  4.c Text descriptions -
  170. The Text Record defines the compressed Text of conText. Text Records and
  171. keyWords  appear  in pairs, With one pair  For each conText in the File.
  172. The Text Record always precedes its associated keyWord. Text Records are
  173. addressed  through  the  File offset values  found  in the conText table
  174. described above.
  175.  
  176. The  RecLength  field  of the Text  Record  header defines the number of
  177. Bytes  of compressed Text in the  Record. The Compression Record defines
  178. how  the Text is compressed. if the Text is nibble encoded, and the last
  179. nibble  of  the  last Byte is not used,  it  is  set to 0. Lines of Text
  180. comprising the the Text Record are stored as null terminated Strings.
  181.  
  182. 4.d  the keyWord Record defines keyWords embedded in the preceeding Text
  183.  Record, and identifies related Text Records.
  184.   The Record begins With the following fixed fields:
  185.     UpConText   : Word;
  186.     DownConText : Word;
  187.     KeyWordCnt  : Word;
  188.  
  189. UpConText  and DownConText give the conText  numbers of the previous and
  190. next  sections of Text in a sequence, either may be zero, indicating the
  191. end of the conText chain.
  192.  
  193. KeyWordCnt  gives the number of keyWords  encoded in the associated Text
  194. Record.  Immediately  following  this  field  is  an  Array  of  KeyWord
  195. Descriptor Records of the following form:
  196.     Type
  197.       TPKwDesc = Record;
  198.         KwConText: Word;
  199.       end;
  200.  
  201. The  keyWords in a Text Record are  numbered from 1 to KeyWordCnt in the
  202. order they appear in the Text (reading left to right, top to bottom).
  203.  
  204. KwConText  is a conText number (index into the conText table) indicating
  205. which conText to switch to if this keyWord is selected by the user.
  206.  
  207.  4.e Index table -
  208. This  is  a list of index descriptors.  An  index is a token (normally a
  209. Word  or name) that has been  explicitly associated With a conText using
  210. the  ;INDEX command in the source Text  File. More than one index may be
  211. associated  With  a conText, but any  given  index can not be associated
  212. With  more than one conText. The list  of index descriptors in the Index
  213. Record  allows  the  Text  of  an index  token  to  be  mapped  into its
  214. associated conText number.
  215.  
  216. The  first Word of the Record gives the number of indexes defined in the
  217. Record.  The  remaining  Bytes  of the  Record  are  grouped  into index
  218. descriptors.  The descriptors are listed in ascending order based on the
  219. Text  of  the  index  token (normal  ascii  collating  sequence). if the
  220. OF_CaseSense  flag  is  not set in the  option  field of the File header
  221. Record, all indexes are in uppercase only.
  222.  
  223.   Each index descriptor Uses the following format:
  224.     LengthCode    : Byte;
  225.     UniqueChars   : Array of Byte;
  226.     ConTextNumber : Word;
  227.  
  228. The  bits  of  LengthCode are divided  into  two  bit fields. Bits(7..5)
  229. specify  the  number of Characters to carry  over  from the start of the
  230. previous  index  token String. Bits(4..0)  specify  the number of unique
  231. Characters to add to the end of the inherited Characters.
  232.  
  233. Field  UniqueChars gives the number of unique Characters to add. e.g. if
  234. the  previous  index  token is `addition',  and  the next index token is
  235. `advanced',  we inherit two Characters from the previous token (ad), and
  236. add six Characters (vanced); thus LengthCode would be $46.
  237.  
  238. ConTextNumber gives the number of the conText associated With the index.
  239. This number is an index into the conText table described above.
  240.  
  241.  4.f A compression Record defines how the contents of Text Records are
  242.   encoded.
  243.      Type
  244.        TPCompress = Record
  245.          CompType : Byte;
  246.          CharTable: Array[0..13] of Byte;
  247.        end;
  248.  
  249.   CompType - nibble encoding is the only compression method currently
  250.              in use.
  251.                      Const CT_Nibble = 2;
  252. The  Text  is  encoded as a stream  of  nibbles.  The nibbles are stored
  253. sequentially;  the low nibble preceeds the high nibble of a Byte. Nibble
  254. values  ($0..$D)  are  direct indexes into  the  CharTable  field of the
  255. compression   Record.  The  indexed  Record  is  the  literal  Character
  256. represented  by  the nibble. The Help  Linker  chooses the 14 (13?) most
  257. frequent  Characters For inclusion in this  table. One exception is that
  258. element 0 always maps to a Byte value of 0.
  259.  
  260.   The remaining two nibble values have special meanings:
  261.           Const
  262.             NC_RawChar = $F;
  263.             NC_RepChar = $E;
  264.  
  265. Nibble  code  NC_Char  introduces two  additional  nibbles that define a
  266. literal Character; the least significant nibble first.
  267.  
  268. Nibble   code  NC_RepChar  defines  a  Repeated  sequence  of  a  single
  269. Character. The next nibble gives the Repeat count less two, (counts 2 to
  270. 17  are possible) The next nibble(s)  define the Character to Repeat; it
  271. can  be  either  a single nibble  in  the range ($0..$D) representing an
  272. index  into  CharTable,  or  it can  be  represented  by  a three nibble
  273. NC_RawChar sequence.
  274.  
  275.  
  276.  4.g RT_IndexTags is in FormatVersion $34 only. This provides a means
  277.   For including index sub headings in the help File.
  278.   The Record header is followed by a list of Variable length tag Records
  279.   Type
  280.     IndRecType = Record;
  281.       windexNumber: Word; {index into the RT_Index Record }
  282.       StrLen: Byte;  {length of tag String(not including terminating 0)}
  283.       szTag: Array[0..0] of Char; {disable range checking}{zero term tag
  284.                                    String}
  285.     end;
  286.    The first structure in the Array is a special entry which has the
  287.    windexnumber set to $FFFF, and contains the default ;DESCRIPTION
  288.    in Case there are duplicate index entries and no tags were specified.
  289. *)
  290.  
  291. Unit HelpGlobals;
  292. { This File contains only the structures which are found in the help Files }
  293.  
  294. Interface
  295.  
  296. Const
  297.   Signature      = '$*$* &&&&*$';   {+ null terminator }
  298.   NC_RawChar     = $F;
  299.   NC_RepChar     = $E;
  300.  
  301. Type
  302.   FileStamp      = Array [0..32] Of Char; {+ null terminator + $1A }
  303.   FileSignature  = Array [0..12] Of Char; {+ null terminator }
  304.  
  305.   TPVersion      = Record
  306.     FormatVersion : Byte;
  307.     TextVersion   : Byte;
  308.   end;
  309.  
  310.   TPRecHdr       = Record
  311.     RecType   : Byte; {TPRecType}
  312.     RecLength : Word;
  313.   end;
  314.  
  315. Const   {RecType}
  316.   RT_FileHeader  = Byte ($0);
  317.   RT_ConText     = Byte ($1);
  318.   RT_Text        = Byte ($2);
  319.   RT_KeyWord     = Byte ($3);
  320.   RT_Index       = Byte ($4);
  321.   RT_Compression = Byte ($5);
  322.   RT_IndexTags   = Byte ($6);
  323.  
  324.  
  325. Type
  326.   TPIndRecType = Record
  327.     windexNumber : Word;
  328.     StrLen       : Byte;
  329.     szTag        : Array [0..0] Of Char;
  330.     { disable range checking}
  331.   end;
  332.  
  333.   TPFileHdrRec = Record
  334.     Options         : Word;
  335.     MainIndexScreen : Word;
  336.     Maxscreensize   : Word;
  337.     Height          : Byte;
  338.     Width           : Byte;
  339.     LeftMargin      : Byte;
  340.   end;
  341.  
  342.  
  343.   TP4FileHdrRec = Record                  {derived from sample File}
  344.     Options    : Word;
  345.     Height     : Byte;
  346.     Width      : Byte;
  347.     LeftMargin : Byte;
  348.   end;
  349.  
  350.   TPCompress = Record
  351.     CompType  : Byte;
  352.     CharTable : Array [0..13] Of Byte;
  353.   end;
  354.  
  355.   TPIndexDescriptor = Record
  356.     LengthCode    : Byte;
  357.     UniqueChars   : Array [0..0] Of Byte;
  358.     ConTextNumber : Word;
  359.   end;
  360.  
  361.   TPKeyWord = Record
  362.     UpConText   : Word;
  363.     DownConText : Word;
  364.     KeyWordCnt  : Word;
  365.   end;
  366.  
  367.   TPKwDesc = Record
  368.     KwConText : Word;
  369.   end;
  370.  
  371.  
  372.   TmyStream = Object(TBufStream) end;
  373.  
  374.   PListRecHdr = ^RListRecHdr;
  375.  
  376.   RListRecHdr = Record
  377.     PNextHdr : PListRecHdr; {Pointer to next list element}
  378.     RRecType : TPRecHdr;    {RecType, RecLength}
  379.     PRecPtr  : Pointer;     {Pointer to copy of Record}
  380.   end;
  381.  
  382.   ConTextRecHd = Record
  383.     NoConTexts  : Word;
  384.     PConTextRec : Pointer;
  385.   end;
  386.  
  387.  
  388. Implementation
  389. end.
  390.  
  391.